Booking Appointment Workflow

Bookadoc integrates with AthenaHealth to allow patients to schedule appointments with healthcare providers. This process involves validating available slots, creating appointments, and ensuring synchronization between both systems.

The booking workflow consists of the following steps:

1. Search for Athena Provider
2. Validate input data (patient ID, provider ID, department ID, appointment type ID)
3. Check if the appointment slot is available
4. Create the appointment in AthenaHealth
5. Store appointment details in Bookadoc
6. Return confirmation to the patient

---

Step 1: Search for Athena Provider

Bookadoc enables patients to search for providers based on the selected visit reason. This process involves:

• Mapping visit reasons to Athena appointment types.
• Fetching available provider appointment slots from Athena.
• Filtering these slots based on appointment type compatibility.

Slot Filtering Logic

After fetching available slots, Bookadoc applies the following logic:

• Only slots matching the selected visit reason's appointmenttypeid are returned
• Generic slots (slots that are marked as usable for any appointment type) are also included.
• This ensures the user only sees slots that are valid for the desired visit reason.

Example Flow

1. User selects "Primary Care Visit"
2. Bookadoc maps this to appointmenttypeid = 1164
3. Bookadoc filters slots to:
   • All slots with appointmenttypeid == 1164
   • All generic slots that accept any visit reason
4. Filtered slots are returned to the frontend for the user to choose.

---

Step 2: Validate Input Data

Before booking an appointment, Bookadoc ensures that all required fields are provided.

Required Fields

Field	Description
patientid	The unique ID of the patient in AthenaHealth
providerid	The ID of the healthcare provider
departmentid	The department where the appointment will take place
appointmenttypeid	The type of appointment (e.g., 15-minute consultation)

If any of these fields are missing, Bookadoc returns an error message prompting the user to provide the necessary details.

---

Step 3: Check Slot Availability

Before creating an appointment, Bookadoc checks whether the selected slot is open.

API Endpoint

GET /v1/{practiceid}/appointments/{appointmentid}

Example Request

GET /v1/12345/appointments/1861676

Response Example

{
  "appointmentid": "1861676",
  "appointmentstatus": "o",
  "starttime": "08:00"
}

If the appointmentstatus is "o" (open), the slot is available for booking. Otherwise, Bookadoc prevents the appointment from being scheduled.

---

Step 4: Create the Appointment

Once the slot is confirmed to be open, Bookadoc sends a request to AthenaHealth to create the appointment.

API Endpoint

POST /v1/{practiceid}/appointments

Request Payload

{
  "appointmentId": "1861676",
  "appointmentData": {
    "patientid": "12345",
    "departmentid": "150",
    "appointmenttypeid": "926",
    "ignoreschedulablepermission": true
  }
}

Response Example

{
  "appointmentid": "1861676",
  "status": "o",
  "starttime": "08:00"
}

If the request is successful, the appointment is created in AthenaHealth, and Bookadoc records the appointment details.

---

Step 5: Store Appointment Details in Bookadoc

After the appointment is booked in AthenaHealth, Bookadoc saves the appointment data in its system to ensure synchronization.

Stored Information

• Appointment ID
• Patient details
• Provider information
• Appointment date and time
• Status (confirmed)

This allows Bookadoc to display upcoming appointments to patients and providers.

---

Step 6: Return Confirmation to Patient

Once the booking is successful, Bookadoc provides a confirmation message to the patient.

Example Confirmation Message

{
  "message": "Your appointment has been successfully booked.",
  "appointmentDetails": {
    "appointmentId": "1861676",
    "date": "02/07/2025",
    "time": "08:00 AM",
    "provider": "Dr. John Doe"
  }
}

Patients receive this confirmation via the Bookadoc platform and (if enabled) email or SMS notifications.

---

Step 7: Reschedule Appointment

Bookadoc handles rescheduling by following a cancel-and-rebook model:

1. Cancel the original appointment in AthenaHealth
2. Book a new appointment with the new time and slot

Validation

• Before rescheduling, Bookadoc checks the cancellation period set for the visit reason’s appointment type.
• If the current time is less than the required notice period (e.g., 24 hours before the appointment), rescheduling is blocked with an appropriate error.

Example Error

{
  "success": false,
  "message": "Too late to reschedule this appointment. Required notice period is 24 hours."
}

Steps

1. GET /appointments/{oldAppointmentId} — Fetch original appointment
2. Validate cancellation period
3. DELETE /appointments/{oldAppointmentId}?cancellationreasonid=XYZ
4. POST /appointments — Create new appointment

---

Step 8: Cancel Appointment

Bookadoc supports canceling appointments by sending a request to Athena with a cancellation reason.

Required Input

• appointmentId — The appointment to be canceled
• cancellationreasonid — The reason for cancellation (must match AthenaHealth reason ID)

Request Example

DELETE /v1/appointments/1861676
{
  "cancellationreasonid": "205"
}

Response

{
  "message": "Appointment cancelled successfully",
  "appointmentId": "1861676"
}

Bookadoc also marks the appointment as cancelled in its own records.

---

Error Handling

If an error occurs at any step, Bookadoc handles it gracefully and provides feedback to the user.

Common Errors & Resolutions

Error Code	Description	Resolution
400 Bad Request	Missing or invalid input fields	Ensure all required fields are provided
409 Conflict	Appointment slot already booked	Prompt user to select another slot
500 Internal Server Error	AthenaHealth API issue	Retry the request after some time

---

Conclusion

The booking appointment workflow ensures that Bookadoc synchronizes seamlessly with AthenaHealth, allowing patients to book available slots while keeping providers' schedules up to date. By validating data, checking availability, and handling errors effectively, Bookadoc enhances the booking experience for both patients and providers.

---